<?php
/**
 * <https://y.st./>
 * Copyright © 2015 Alex Yst <mailto:copyright@y.st>
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <https://www.gnu.org./licenses/>.
**/

$xhtml = array(
	'<{title}>' => 'Wrapper classes',
	'<{body}>' => <<<END
<p>
	This morning, I awoke to find that our home&apos;s Internet connection was down.
	Everything seems to be fine on our end, leading me to believe that the problem is on our $a[ISP]&apos;s side.
	In any case, it got me thinking.
	I am pretty helpless without the Internet.
	This morning, I was not able to accomplish anything of note.
	I could not test my email client to see if everything is in order now.
	I could have worked on my search engine spider, but the point of that thing is to learn.
	I do not already know the functions and parameters I need in order to make it work.
	Without access to the online $a[PHP] manual, I could not continue progress.
	Likewise, I considered starting a small project to fill the time by building wrapper classes for as many $a[PHP] function sets as I could that pass around a resource.
	However, again, I would need the $a[PHP] manual in order to find and understand these function sets.
	I could not work on the $a[IRC] server either, as it appears that I do not have the software needed to do so.
	The $a[IRC] server is up and running perfectly already, so the only thing left to do is get services running.
	My current services software is incompatible with my current $a[IRC] daemon though.
	I need to install a new services package and/or a new $a[IRC] daemon, which requires retrieving it or them from the Internet.
	At the very least, I need to download the $a[PHP] manual.
	I can put one copy of it at <code>https://php.test/</code> for easy use when my local network is functioning but we cannot access the greater Internet, as well as a second copy on my laptop hard drive, where it willl not be as convenient to use, but will be perfectly accessible even when I have no connection at all.
</p>
<p>
	While trying to figure out what to do with myself, I realized that the $a[PHP] wrapper class would be a good project for me.
	While it would be incredibly simple, it would also teach me about the different resource types available in $a[PHP].
	At the very least, I make direct use of two different resource types in my code, and I really should clean that up with some object-oriented code.
	I also think that I should move my wrapper classes to a sub-namespace, making them easy to identify both in my code and in my directory tree.
	That was when it hit me.
	I could download the $a[PHP] manual on my mobile, then transfer it to my laptop over $a[MTP].
</p>
<p>
	I thought that I would need to grep the manual to find informations on all the resource-using functions, but much to my delight, <code>./php-chunked-xhtml/resource.html</code> has a list of them.
	Most of the entries on the table there have hyperlinks to the sections of the manual that document the functions, though a few do not.
	Having no access to the Internet on my laptop, it was easiest to just assume that the links were not present due to there not being any entries in the manual, and instead focus only on the resource types that did offer links to their related functions.
</p>
<p>
	First, I made the modifications necessary to move my existing wrapper class, the one for $a[cURL] resources, into the sub-namespace.
	After that, I turned my focus to attention on $a[GnuPG] handles.
	Much to my surprise though, the <code>gnupg_init()</code> function and the handles that it creates were not mentioned in the manual.
	I would have suspected that functions that are not built-into $a[PHP] are mentioned only on the online manual if not for the fact that $a[cURL] resource handle and accompanying functions are in fact listed in this manual.
	In any case, adding a wrapper class to $a[GnuPG] would have to wait until I had Internet access again.
	My next target was the objects output by the <code>dir()</code> function.
	According to the manual, <code>dir()</code> is only used as pseudo-object oriented method of accessing directories.
	However, I found that the class of objects output by this function is completely legitimate.
	Unlike the class used by closures, you can even instantiate this class with the <code>new</code> key word.
	It even has all the functions that one would expect it to have, with the exception of two: a constructor and a destructor.
	The <code>dir()</code> function acts as a sort of pseudo-constructor though, and a destructor is not strictly needed.
	I decided not to try extending this class, as it would pretty much just mean changing the line <code>\$var = dir(\$file);</code> into the longer line <code>\$var = new dir(\$file);</code>, which would need to be preceded by a second line reading <code>use st\\y\\wrapper\\dir;</code> for the first line to even be that short.
	My guess from reading the documentation is that the <code>dir()</code> function basically acts like this:
</p>
<p>
	<code>{$syntax('<?php
function dir($directory, $context=null) {
	$new = new Dir;
	$new->path = $directory;
	$new->handle = opendir($directory, $context);
return $new; }', true)}</code>
</p>
<p>
	It might have some input checks in it unlike the code above, but aside from that, I think that it behaves about the same way.
</p>
<p>
	Before I could get any actual new classes written, I was whisked away to work in my mother&apos;s classroom for most of the day.
	On the bright side though, it sounds like I can probably go to Portland with Vivian with minimal problems attached! I will likely stay there for three weeks.
	During that time, I may or may not be able to update my canary.
	This should be awesome though, I will get to see what she is doing to make a difference in the world and hopefully even help.
</p>
<p>
	It looks like I was not the only one having mail issues, but Zoho <a href="https://forums.zoho.com/topic/error-fetching-folders-syntax-expecting-s-found-c">fixed the problem</a>! It looks like tha other two users that joined the conversation were using the same mail client as I, though I did not mention what mail client I use.
	After posting about the issue, I realized that I should have mentioned that I was using an $a[IMAP] client.
</p>
<p>
	While out today, I realized that I should work on the directory wrapper, despite my initial decision not to.
	In the case of the way that the built-in directory class and directory functions work, they are really only useful when a complex iterative loop is built around them.
	The class should be able to iterate over itself, or at least work well in a simple loop.
	I quickly found the likely reason that iteration was not included in the built-in class though.
	The directory resource handles are not built in a way that makes using the Iterator interface easy.
	Putting these wrapper classes together has proven to be quite boring though, so I do not think I want to sit down and complete them all at once.
	Instead, I will make sure to complete at least one to throw in with each regular update I perform on my library.
</p>
<p>
	I found a <a href="https://secure.php.net/manual/en/ref.dbx.php">dbx extension for $a[PHP]</a> in the manual while looking for functions that need to be wrapped.
	The documentation says that instead of a resource, an object is passed around between functions.
	Why are these functions not made object methods? It might be worth extending the class used and add the methods in, but testing the name of the class used is undocumented and and finding out from $a[PHP] itself would require setting up some sort of database so that the class can be successfully instantiated using the provided functions and the object class checked with the <a href="https://secure.php.net/manual/en/function.get-class.php"><code>get_class()</code> function</a>.
	I only managed to get four new wrapper classes built today, but I will continue the project later.
</p>
<p>
	My <a href="/a/canary.txt">canary</a> still sings the tune of freedom and transparency.
</p>
<section id="docmod">
	<h2>Document modifications</h2>
	<p>
		On <a href="/en/weblog/2018/01-January/16.xhtml#Vivian">2018-01-16</a>, my sister, Vivian, requested that I replace all instances of her legal name in my journal with the name &quot;Vivian&quot;.
		She also asked that the name of the organisation she works for be redacted.
		This page was modified to fulfil that request.
	</p>
</section>
END
);
